'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2012 Joshua M. Clulow <josh@sysmgr.org>
.\" Copyright 2019 Peter Tribble
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH FMADM 8 "Jan 14, 2020"
.SH NAME
fmadm \- fault management configuration tool
.SH SYNOPSIS
.nf
\fBfmadm\fR [\fB-q\fR] [\fIsubcommand\fR [\fIarguments\fR]]
.fi

.SH DESCRIPTION
The \fBfmadm\fR utility can be used by administrators and service personnel to
view and modify system configuration parameters maintained by the Fault
Manager, \fBfmd\fR(8). \fBfmd\fR receives telemetry information relating to
problems detected by the system software, diagnoses these problems, and
initiates proactive self-healing activities such as disabling faulty
components.
.sp
.LP
\fBfmadm\fR can be used to:
.RS +4
.TP
.ie t \(bu
.el o
view the set of diagnosis engines and agents that are currently participating
in fault management,
.RE
.RS +4
.TP
.ie t \(bu
.el o
view the list of system components that have been diagnosed as faulty, and
.RE
.RS +4
.TP
.ie t \(bu
.el o
perform administrative tasks related to these entities.
.RE
.sp
.LP
The Fault Manager attempts to automate as many activities as possible, so use
of \fBfmadm\fR is typically not required. When the Fault Manager needs help
from a human administrator, it produces a message indicating its needs. It also
refers you to a knowledge article on http://illumos.org/msg/. This web site
might ask you to use \fBfmadm\fR or one of the other fault management utilities
to gather more information or perform additional tasks. The documentation for
\fBfmd\fR(8), \fBfmdump\fR(8), and \fBfmstat\fR(8) describe more about tools
to observe fault management activities.
.sp
.LP
The \fBfmadm\fR utility requires the user to possess the \fBPRIV_SYS_ADMIN\fR
privilege. See \fBprivileges\fR(7). The \fBfmadm\fR \fBload\fR subcommand
requires that the user possess all privileges.
.SS "SUBCOMMANDS"
\fBfmadm\fR accepts the following subcommands. Some of the subcommands accept
or require additional options and operands:
.sp
.ne 2
.na
\fB\fBfmadm acquit\fR \fIfmri\fR \fB|\fR \fIlabel\fR [\fIuuid\fR]\fR
.ad
.sp .6
.RS 4n
Notify the Fault Manager that the specified resource is not to be considered to
be a suspect in the fault event identified by \fIuuid\fR, or if no UUID is
specified, then in any fault or faults that have been detected. The \fBfmadm
acquit\fR subcommand should be used only at the direction of a documented
repair procedure. Administrators might need to apply additional commands to
re-enable a previously faulted resource.
.RE

.sp
.ne 2
.na
\fB\fBfmadm acquit\fR \fIuuid\fR\fR
.ad
.sp .6
.RS 4n
Notify the Fault Manager that the fault event identified by \fIuuid\fR can be
safely ignored. The \fBfmadm acquit\fR subcommand should be used only at the
direction of a documented repair procedure. Administrators might need to
apply additional commands to re-enable any previously faulted resources.
.RE

.sp
.ne 2
.na
\fB\fBfmadm config\fR\fR
.ad
.sp .6
.RS 4n
Display the configuration of the Fault Manager itself, including the module
name, version, and description of each component module. Fault Manager modules
provide services such as automated diagnosis, self-healing, and messaging for
hardware and software present on the system.
.RE

.sp
.ne 2
.na
\fB\fBfmadm faulty\fR [\fB-afgiprsv\fR] [\fB-n\fR \fImax\fR] [\fB-u\fR
\fIuuid\fR]\fR
.ad
.sp .6
.RS 4n
Display status information for resources that the Fault Manager currently
believes to be faulty.
.sp
The following options are supported:
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.RS 10n
Display all faults. By default, the \fBfmadm faulty\fR command only lists
output for resources that are currently present and faulty. If you specify the
\fB-a\fR option, all resource information cached by the Fault Manager is
listed, including faults which have been automatically corrected or where no
recovery action is needed. The listing includes information for resources that
might no longer be present in the system.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 10n
Display faulty \fBfru's\fR (Field replaceable units).
.RE

.sp
.ne 2
.na
\fB\fB-g\fR\fR
.ad
.RS 10n
Group together faults which have the same fru, class and fault message.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR\fR
.ad
.RS 10n
Display persistent cache identifier for each resource in the Fault Manager.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR \fImax\fR\fR
.ad
.RS 10n
If faults or resources are grouped together with the \fB-a\fR or \fB-g\fR
options, limit the output to \fImax\fR entries.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 10n
Pipe output through pager with form feed between each fault.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.RS 10n
Display Fault Management Resource with their Identifier (FMRI) and their fault
management state.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 10n
Display 1 line fault summary for each fault event.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR \fIuuid\fR\fR
.ad
.RS 10n
Only display fault with given \fBuuid\fR.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 10n
Display full output.
.RE

The percentage certainty is displayed if a fault has multiple suspects, either
of different classes or on different \fBfru\fR's. If more than one resource is
on the same \fBfru\fR and it is not 100% certain that the fault is associated
with the \fBfru\fR, the maximum percentage certainty of the possible suspects
on the \fBfru\fR is displayed.
.RE

.sp
.LP
The Fault Manager associates the following states with every resource for which
telemetry information has been received:
.sp
.ne 2
.na
\fB\fBok\fR\fR
.ad
.sp .6
.RS 4n
The resource is present and in use and has no known problems so far as the
Fault Manager is concerned.
.RE

.sp
.ne 2
.na
\fB\fBunknown\fR\fR
.ad
.sp .6
.RS 4n
The resource is not present or not usable but has no known problems. This might
indicate the resource has been disabled or deconfigured by an administrator.
Consult appropriate management tools for more information.
.RE

.sp
.ne 2
.na
\fB\fBfaulted\fR\fR
.ad
.sp .6
.RS 4n
The resource is present but is not usable because one or more problems have
been diagnosed by the Fault Manager. The resource has been disabled to prevent
further damage to the system.
.RE

.sp
.ne 2
.na
\fB\fBdegraded\fR\fR
.ad
.sp .6
.RS 4n
The resource is present and usable, but one or more problems have been
diagnosed in the resource by the Fault Manager.
.sp
If all affected resources are in the same state, this is reflected in the
message at the end of the list. Otherwise the state is given after each
affected resource.
.RE

.sp
.ne 2
.na
\fB\fBfmadm flush\fR \fIfmri\fR\fR
.ad
.sp .6
.RS 4n
Flush the information cached by the Fault Manager for the specified resource,
named by its FMRI. This subcommand should only be used when indicated by a
documented repair procedure. Typically, the use of this command is not
necessary as the Fault Manager keeps its cache up-to-date automatically. If a
faulty resource is flushed from the cache, administrators might need to apply
additional commands to enable the specified resource.
.RE

.sp
.ne 2
.na
\fB\fBfmadm load\fR \fIpath\fR\fR
.ad
.sp .6
.RS 4n
Load the specified Fault Manager module. \fIpath\fR must be an absolute path
and must refer to a module present in one of the defined directories for
modules. Typically, the use of this command is not necessary as the Fault
Manager loads modules automatically when the operating system initially boots
or as needed.
.RE

.sp
.ne 2
.na
\fB\fBfmadm unload\fR \fImodule\fR\fR
.ad
.sp .6
.RS 4n
Unload the specified Fault Manager module. Specify \fImodule\fR using the
basename listed in the \fBfmadm config\fR output. Typically, the use of this
command is not necessary as the Fault Manager loads and unloads modules
automatically based on the system configuration
.RE

.sp
.ne 2
.na
\fB\fBfmadm repaired\fR \fIfmri\fR \fB|\fR \fIlabel\fR\fR
.ad
.sp .6
.RS 4n
Notify the Fault Manager that a repair procedure has been carried out on the
specified resource. The \fBfmadm repaired\fR subcommand should be used only at
the direction of a documented repair procedure. Administrators might need
to apply additional commands to re-enable a previously faulted resource.
.RE

.sp
.ne 2
.na
\fB\fBfmadm replaced\fR \fIfmri\fR \fB|\fR \fIlabel\fR\fR
.ad
.sp .6
.RS 4n
Notify the Fault Manager that the specified resource has been replaced. This
command should be used in those cases where the Fault Manager is unable to
automatically detect the replacement. The \fBfmadm replaced\fR subcommand
should be used only at the direction of a documented repair procedure.
Administrators might need to apply additional commands to re-enable a
previously faulted resource.
.RE

.sp
.ne 2
.na
\fB\fBfmadm reset\fR [\fB-s\fR \fIserd\fR\fB]\fR \fImodule\fR\fR
.ad
.sp .6
.RS 4n
Reset the specified Fault Manager module or module subcomponent. If the
\fB-s\fR option is present, the specified Soft Error Rate Discrimination (SERD)
engine is reset within the module. If the \fB-s\fR option is not present, the
entire module is reset and all persistent state associated with the module is
deleted. The \fBfmadm reset\fR subcommand should only be used at the direction
of a documented repair procedure. The use of this command is typically not
necessary as the Fault Manager manages its modules automatically.
.RE

.sp
.ne 2
.na
\fB\fBfmadm rotate\fR \fBerrlog | fltlog\fR\fR
.ad
.sp .6
.RS 4n
The \fBrotate\fR subcommand is a helper command for \fBlogadm\fR(8), so that
\fBlogadm\fR can rotate live log files correctly. It is not intended to be
invoked directly. Use one of the following commands to cause the appropriate
logfile to be rotated, if the current one is not zero in size:
.sp
.in +2
.nf
# \fBlogadm -p now -s 1b /var/fm/fmd/errlog\fR
# \fBlogadm -p now -s 1b /var/fm/fmd/fltlog\fR
.fi
.in -2
.sp

.RE

.SH OPTIONS
The following options are supported:
.sp
.ne 2
.na
\fB\fB-q\fR\fR
.ad
.RS 6n
Set quiet mode. \fBfmadm\fR does not produce messages indicating the result of
successful operations to standard output.
.RE

.SH OPERANDS
The following operands are supported:
.sp
.ne 2
.na
\fB\fIcmd\fR\fR
.ad
.RS 8n
The name of a subcommand listed in \fBSUBCOMMANDS\fR.
.RE

.sp
.ne 2
.na
\fB\fIargs\fR\fR
.ad
.RS 8n
One or more options or arguments appropriate for the selected \fIsubcommand\fR,
as described in \fBSUBCOMMANDS\fR.
.RE

.SH EXIT STATUS
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 5n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 5n
An error occurred. Errors include a failure to communicate with \fBfmd\fR or
insufficient privileges to perform the requested operation.
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.RS 5n
Invalid command-line options were specified.
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	See below.
.TE

.sp
.LP
The command-line options are Committed. The human-readable output is
not-an-interface.
.SH SEE ALSO
.BR attributes (7),
.BR privileges (7),
.BR fmd (8),
.BR fmdump (8),
.BR fmstat (8),
.BR logadm (8),
.BR syslogd (8)
.sp
.LP
http://illumos.org/msg/
